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ABSTRACT 

This  paper  describes  the  library  of  routines  written  in  C  language 
under  UNIX  on  a  PDP-11/34  for  operating  the  NORPAK  VDP/RGS  (raster)  and  VDP/VGS 
(vector)  colour  graphic  displays.  The  details  of  the  routines  which  are 
pertinent  to  the  user  are  described.  A  listing  of  the  library  of  routines  is 
included . 


RESUME 

Ce  document  decrit  une  bibliotheque  de  programmes  ecrit  dans  le 
langage  C  du  systeme  UNIX  PDP-11/ 34  qui  permet  le  fonctionnement  des  ecrans 
couleur  Norpak  VDP/RGS  (trame)  et  VDP/VGS  (vecteur)  pour  representation 
graphique.  Les  details  des  programmes  propres  a  1 f utilisateur  ainsi  qu'une 
liste  de  la  bibliotheque  de  programmes  y  sont  inclus. 
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1,0  INTRODUCTION 


The  graphics  display  library  is  a  series  of  routines  that  provide  a 
means  of  defining  what  will  be  on  the  colour  display  (the  Visual  Data  Processor 
(VDP)  controlling  a  Raster  Graphics  Subsystem  (RGS)  and  Vector  Graphics  Sub¬ 
system  (VGS)).  The  routines  are  written  in  the  C  language  running  under  UNIX 
on  a  PDP-11/ 34  computer.  When  a  program  to  create  a  display  is  compiled,  this 
library  of  display  routines  is  appended  to  the  main  program.  This  display  pro¬ 
gram  would  have  a  number  of  calls  to  a  subset  of  these  library  routines. 

The  set  up  of  the  system  of  display  routines  was  developed  to  improve 
the  speed  of  response  time  over  the  NORPAK-supplied  routines  which  were  TELIDON 
oriented.  These  routines  had  no  optimization  for  the  high  resolution  Visual 
Data  Processor  (VDP),  were  very  general,  and  used  a  very  slow  processor. 

The  graphics  display  library  routines  were  patterned  after  a  similar 
set  written  in  assembler  for  the  CANEWS  project  implemented  on  a  UYK-20 
computer.  A  different  host  processor  (PDP-11/34)  necessitated  design  changes. 
Although  the  code  for  the  UYK-20  routines  was  not  used,  much  of  the  philosophy 
is  the  same.  The  design  was  extended  to  allow  the  same  routines  to  be  used  on 
the  VGS  (Vector  Graphics  Subsystem)  or  the  RGS  (Raster  Graphics  Subsystem). 

The  library  of  routines  allows  a  large  portion  of  the  display  contents 
to  be  predefined  and  display  changes  to  be  made  quickly.  This  is  because  the 
graphical  definitions  reside  in  the  VDP,  waiting  for  portions  to  be  selected 
for  display.  This  minimizes  the  amount  of  data  flowing  between  the  host 
processor  and  the  VDP. 

This  programming  guide  assumes  a  knowledge  of  the  UNIX  operating 
system  and  the  C  language. 

\ 

2.0  THE  PHASES 


The  graphics  display  library  (gdlib.c)  is  divided  into  four  phases: 

1)  initialization  phase 

2)  subpicture  definition  phase 

3)  group  definition  phase 

4)  display  phase 

Programs  accessing  the  graphics  display  library  must  acknowledge  each 
of  these  phases. 

2.1  Initialization  Phase 

The  initialization  phase  conists  of  a  call  to  gdinit(  ).  This 
routine  initializes  variables,  the  terminal  and  the  character  spacing.  It  is 


in  this  phase  that  the  user  decides  whether  to  use  the  RGS  (unit  0)  or  the  VGS 
(unit  1).  The  unit  value  defaults  to  0  but  may  be  set  to  1  if  desired. 


2.2  Subpicture  Definition  Phase 

The  subpicture  definition  phase  immediately  follows  the  initialization 
phase.  It  is  not  necessary  to  have  any  subpictures  defined  but  a  call  to 
gdsubend(  )  to  end  the  phase  is  required.  There  may  be  many  subpictures  defined 
each  one  starts  with  a  call  to  gdsubopn(  )  to  open  the  subpicture  and  ends  with 
a  call  to  gdsubcls(  )  to  close  the  subpicture.  Once  subpictures  have  been 
defined  they  cannot  be  edited.  A  subpicture  describes  a  picture  element  that 
will  likely  be  repeated  more  than  once  in  the  display.  Subpictures  would  be 
used  mainly  to  define  special  symbols,  (eg.  the  symbol  for  an  aircraft). 

The  body  of  the  subpicture  consists  of  any  combination  of  calls  to 
gdcolr (  ),  gdints (  ),  gdblnk(  ),  gdaset(  ),  gdcset(  ),  gdvect(  ),  gdivec(  ), 
gdtext(  ).  These  routines  are  definition  commands  and  will  be  described  later. 
Calls  to  gdcolr (  )  are  not  recommended  on  the  VGS  because  considerable  time 
is  taken  to  switch  colours.  When  the  VDP  displays  the  screen  it  sorts  by 
colour  then  displays  all  of  one  colour  at  a  time.  However,  colours  in  sub¬ 
pictures  can  not  be  accessed  to  sort. 

A  subpicture  is  restricted  to  1024,  16  bit  words  of  data  in  total. 

The  call  to  gdsubend(  )  is  required  whether  there  are  any  subpictures  defined 
or  not. 


2. 3  Group  Definition  Phase 

The  group  definition  phase  immediately  follows  the  subpicture 
definition  phase.  This  phase  is  terminated  by  a  call  to  gdgrpend(  ).  At 
least  one  group  must  be  defined.  These  groups  contain  the  commands  that 
describe  what  will  be  on  the  display. 

A  group  definition  consists  of  zero  or  more  calls  to  gdcolr (  ), 
gdints(  ),  gdblnk(  ),  gdaset(  ),  gdcset(  );  and  one  or  more  calls  to  any  one 
of  the  three  types  of  drawing  commands:  gdvect(  )  or  gdivec(  ),  gdtext(  ), 
gdsubp(  ).  A  group  can  have  one  of  the  text,  vector  or  subpicture  drawing 
commands  but  not  more  than  one  type.  The  drawing  commands  gdvect(  )  and 
gdivec(  )  may  be  intermixed  since  they  are  both  vector  drawing  commands  even 
though  the  latter  draws  invisible  vectors. 

The  calls  to  the  definition  commands  simply  reset  the  default 
attributes  assigned  to  the  group.  When  the  gdgrpend(  )  call  is  made  the 
attributes  are  filled  into  the  group  header  along  with  the  drawing  commands, 
and  output. 


2.4  Display  Phase 

The  display  phase  immediately  follows  the  group  definition  phase. 
This  phase  is  terminated  by  another  gdinit(  ).  If  the  calling  program 
terminates  without  another  gdinit(  )  then  the  picture  will  remain  displayed 
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until  the  screen  is  accessed  by  another  program. 

This  phase  consists  of  calls  to  gdattach(  ),  gdupdate(  ),  gdcursor(  ), 
gdpoll(  ),  gddisply(  )  and  calls  to  any  of  the  edit  group.  Descriptions  of 
all  of  these  routines  follow.  These  calls  may  be  made  in  any  order,  depending 
on  application. 

3.0  THE  COMMANDS 

The  commands  are  the  actual  routines  that  will  be  called  by  the  user’s 
program  to  draw  on  the  display. 


3.1  Control  Commands 


gdinit (  ): 


This  routine  sets  up  a  line  of  communication  with  the  VGS  or  the  RGS. 
Variables,  the  terminal  and  character  spacing  are  initialized. 

gdsubopn(  ): 

This  routine  indicates  a  subpicture  definition  will  begin.  The 
routine  check?  that  the  phase  is  correct  to  open  a  subpicture,  and 
that  there  is  not  an  unclosed  subpicture.  Once  a  subpicture  is 
defined  it  cannot  be  edited.  The  routine  keeps  track  of  the  number 
of  subpictures. 

gdsubcls(  ): 

This  routine  indicates  the  current  subpicture  definition  will  end. 

The  routine  checks  that  the  phase  is  correct  to  close  a  subpicture 
and  that  there  is  indeed  an  open  subpicture  to  close.  If  so,  the 
subpicture  information  is  written  to  the  VDP. 


gdsubend(  ): 


This  routine  marks  the  end  of  the  subpicture  definition  phase.  The 
routine  checks  that  all  subpictures  that  have  been  opened  have  been 
closed.  If  not,  an  error  is  indicated.  If  the  state  is  correct  to 
end  the  subpicture  phase  it  is  changed  to  group  phase  and  the  group 
neader  information  Is  set  up  so  the  group  definition  phase  may  begin. 
Initially  the  group  colour  is  red,  the  intensity  is  full,  the 
screen  is  not  blinking,  the  drawing  pointer  is  set  to  (0,0),  and  the 
small  character  set  is  in  use. 

gdgrpopn (  ): 

This  routine  is  called  to  begin  definition  of  a  group.  It  checks 
that  the  phase  is  the  group  definition  phase;  and  it  checks  that 
there  is  not  an  unclosed  group.  The  routine  keeps  track  of  the 
number  of  groups  defined.  Each  group  may  define  text,  or  vectors 
(visible  and  invisible),  or  subpicture  calls;  but  may  not  define  a 
combination  of  these. 
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gdgrpcls( 


gdgrpend ( 


gdupdate( 


gdpoll (  ) 


gddisply ( 


gdcursor ( 


gdattach( 


): 

This  routine  closes  the  definition  of  a  group*  The  routine  checks 
that  the  phase  is  correct  to  close  a  group  definition  and  that  there 
is  indeed  an  open  group  to  close.  If  so,  the  number  of  drawing 
commands  in  this  group  is  recorded,  and  the  group  information  is 
sent  to  the  VDP. 

): 

This  routine  marks  the  end  of  the  group  definition  phase.  The 
routine  checks  that  all  groups  that  have  been  opened  have  been 
closed.  The  phase  is  checked  and  if  it  is  correct  (phase  3  -  group 
definition  phase)  then  the  program  may  proceed  to  the  display  phase. 

): 

This  routine  updates  the  display  with  the  given  list  of  groups.  The 
groups  are  presented  in  an  array  along  with  the  number  of  groups 
included.  The  information  is  sent  to  the  VDP.  If  the  program  is 
not  in  the  display  phase  an  error  is  indicated. 


This  routine  polls  for  the  co-ordinates  of  the  cursor.  The  cursor 
is  attached  to  the  trackball.  The  x  position  and  the  y  position  of 
the  cursor  are  each  read  into  corresponding  variables.  If  the 
program  is  not  in  the  display  phase  at  the  time  of  the  call  the 
error  is  indicated. 

): 

This  routine  turns  the  display  refresh  on  or  off.  The  routine  is 
used  for  the  VGS  since  the  vector  system  constantly  refreshes  the 
screen  but  the  RGS  has  no  need  to  do  so.  If  the  program  is  not  in 
the  display  phase  at  the  time  of  the  call  an  error  is  indicated. 

): 

This  routine  turns  the  trackball  cursor  on  or  off.  The  program  must 
be  in  the  display  phase. 


): 


A  group  defines  the  shape  and  size  of  the  cursor,  and  in  order  to 
display  the  cursor  that  group  must  be  selected  for  display  through 
the  last  update  command  (gdupdate(  )).  The  routine  attaches  the 
trackball  to  the  group  defining  the  cursor.  The  gdaset(  )  value  in 
the  defining  group  is  the  actual  position  of  the  cursor.  The 
information  is  sent  to  the  VDP.  The  program  must  be  in  the  display 
phase. 


3.2  Subpicture  and  Group  Definition  Drawing  Commands 


gdcolr ( 


gdints( 


gdblnk( 


gdaset ( 


This  routine  defines  the  subpicture  colour  if  in  the  subpir.ture 
definition  phase,  or  changes  the  colour  value  in  the  group  header 
if  in  the  group  definition  phase.  If  not  in  either  of  these  phases 
an  error  is  indicated.  The  possible  colours  are: 

0  -  red 

1  -  orange 

2  -  amber 

3  -  yellow 

4  -  green 

(Note;  the  RGS  allows  variations  in  blue  and  purple  as  well,  but  as 
the  aim  was  to  make  the  RGS  and  VGS  work  with  the  same  library  of 
routines,  the  RGS  had  to  limit  its  colours  to  those  of  the  VGS.) 


This  routine  defines  the  intensity  of  the  information  displayed  on 
the  screen  if  in  the  subpicture  phase,  or  changes  the  intensity  value 
in  the  group  header  if  in  the  group  definition  phase.  If  not  in 
either  of  these  phases  an  error  is  indicated.  The  possible 
intensities  are  0  to  17  octal  with  17  being  full  intensity  and  0 
being  invisible.  The  parameter  passed  to  this  routine  should  contain 
the  intensity. 


This  routine  indicates  whether  or  not  the  subpicture  elements  will 
blink  if  in  the  subpicture  definition  phase;  or  the  routine  changes 
the  blink  status  in  the  group  header  if  in  the  group  definition  phase. 
If  not  in  either  phase  an  error  is  indicated.  The  blink  status: 

0  -  do  not  blink 
1  -  blink 


This  routine  sets  up  the  absolute  x,  y  position  from  which  the  next 
information  will  be  drawn.  In  the  subpicture  definition  phase  the 
x,  y  set  is  defined.  In  the  group  definition  phase  the  x,  y  set 
is  modified  in  the  header.  If  in  neither  of  the  phases  an  error  is 
indicated,  x  and  y  must  be  greater  than  or  equal  0,  and  x  and  y 
must  be  less  than  or  equal  1023.  Each  group  can  only  do  one 
absolute  position  set.  If  a  group  does  not  do  an  absolute  position 
set  then  the  set  from  the  immediately  preceding  group  is  used. 
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gdcset(  ): 

This  routine  defines  the  subpicture  character  set  choice  if  in  the 
subpicture  definition  phase,  or  modifies  the  character  set  choice 
if  in  the  group  definition  phase.  If  in  neither  of  these  phases  an 
error  is  indicated.  The  character  set  choice  is: 

0  -  small 
1  -  large 

gdvect(  ): 

This  routine  sets  up  a  series  of  one  or  more  relative  vectors  to  be 
drawn  one  after  the  other.  The  array  of  vectors  may  be  introduced 
in  either  a  subpicture  or  a  group.  If  the  program  is  neither  in 
the  subpicture  definition  phase  nor  the  group  definition  phase  an 
error  is  indicated.  The  array  of  vectors  and  the  size  of  the  array 
must  be  given. 

gdivec(  ): 

This  routine  sets  up  a  series  of  one  or  more  invisible  relative 
vectors  to  be  drawn  one  after  another.  The  array  of  vectors  may  be 
introduced  in  either  a  subpicture  or  a  group.  If  the  program  is 
currently  neither  in  the  subpicture  definition  phase  nor  in  the  group 
definition  phase  an  error  is  indicated.  The  array  of  vectors  and 
the  size  of  the  array  must  be  given.  Invisible  vectors  may  be  used 
if  one  requires  the  x,  y  pointer  position  to  be  at  another  location 
on  the  screen  but  does  not  wish  to  start  another  group. 

gdtext (  ): 

This  routine  defines  a  text  string  to  be  written  on  the  display,  in 
either  a  subpicture  or  a  group.  If  the  program  is  neither  in  the 
subpicture  definition  phase  nor  in  the  group  definition  phase  an  error 
is  indicated.  The  string  of  characters  will  be  sent  as  follows: 
gdtext  ("ABC",  3).  The  string  and  the  length  of  the  string  (including 
blanks)  must  be  indicated.  Note:  the  string  can  also  be  given  in 
an  array. 

gdsubp(  ): 


This  routine  indicates  which  subpicture  will  be  accessed  from  the 
present  group.  If  the  program  is  not  in  the  group  definition  phase 
an  error  is  indicated.  As  subpictures  were  defined  they  were 
numbered,  starting  at  1.  The  subpictures  to  be  accessed  are  to  be 
indicated  using  these  numbers.  These  numbers  are  introduced  in 
the  group  as  an  array.  The  size  of  this  array  must  also  be  given. 
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3.3  Group  Edit  Commands 

After  the  screen  has  been  displayed  portions  may  need  changing. 

This  is  done  by  editing  the  desired  groups  and  then  redisplaying  the  screen 
using  the  gdupdate(  )  command.  In  each  edit  command  the  group  to  be  edited 
must  be  indicated,  along  with  the  new  value(s)  of  what  is  being  edited.  Grou;  s 
were  numbered  from  1  as  they  were  created.  They  are  identified  using  this 
number.  The  edit  type  must  also  be  given: 


0  -  if  the  template  is  to  be  edited 

1  -  if  the  template  and  the  display  are  to  be  edited 

When  the  display  is  edited  (edit  type  =  1)  an  automatic  update  of  the  display 
occurs. 

gdedcolr(  ): 

This  routine  edits  a  group's  colour. 
gdedints(  ): 

This  routine  edits  a  group's  intensity. 
gdedblnk(  ) : 

This  routine  edits  whether  or  not  the  information  in  the  group  will 
blink. 


gdedaset(  ): 

This  routine  edits  the  group's  absolute  xf  y  pointer  position. 
6uedcset(  ): 

This  routine  edits  the  group's  choice  of  character  size. 
gdedvect(  ): 

This  routine  edits  a  number  of  vectors  (0  or  more)  in  a  given  group. 
The  vectors  to  be  modified  are  presented  in  ar  array.  The  size  of 
this  array  must  be  given.  Each  array  must  be  of  contiguous  vectors. 
The  number  of  the  first  vector  to  be  changed  must  be  given.  There 
may  be  more  than  one  call  to  gdedvect(  )  for  a  given  group.  This 
may  be  necessary  since  all  vectors  to  be  changed  are  not  likely 
contiguous. 


gdedivec(  ): 


This  routine  is  like  gdedvect(  )  but  the  vectors  are  invisible 
vectors. 
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gdedtext(  ): 

This  routine  edits  a  series  of  contiguous  characters  of  a  text  string. 
The  number  of  the  first  character  of  the  series  must  be  given  to  the 
routine  along  with  the  number  of  characters  in  the  series  to  be 
changed.  Of  course  the  new  string  of  characters  must  also  be  given. 
Since  the  text  edit  is  a  one  for  one  character  replacement  the  new 
string  must  be  the  same  length  as  the  old  string.  There  may  be  more 
than  one  gdedtext(  )  call  per  group. 

gdedsubp(  ): 

This  routine  edits  the  subpictures  to  be  called  from  the  group. 

The  subpictures  are  presented  in  an  array.  The  size  of  the  array 
must  be  given.  The  subpictures  to  be  edited  must  be  contiguous,  and 
the  number  of  the  first  subpicture  of  the  set  must  be  given.  There 
may  be  more  than  one  gdedsubp(  )  call  per  group. 


4.0  CONCLUSIONS 


Appendix  A  is  a  complete  listing  of  the  library  of  display  routines. 

Although  the  display  routines  do  not  include  specialized  routines 
such  as  a  routine  to  draw  dashed  lines  and  a  routine  to  draw  a  circle,  the 
routines  are  simple,  straightforward  and  easy  to  use.  Using  the  routines  in 
the  library,  it  is  a  straightforward  matter  to  write  the  specialized  routines. 
Once  these  routines  are  written  they  can  be  compiled  along  with  the  calling 
program  or  added  to  the  display  library. 

Consistency  among  the  library  routines  was  emphasized.  For  example 
all  information  for  vectors,  groups,  strings,  and  subpictures  must  be  presented 
as  arrays. 


It  is  beneficial  that  the  same  routines  can  be  used  to  display  on 
the  raster  CRT  or  the  vector  CRT,  with  the  differences  in  manipulating  the 
two  transparent  to  the  user. 

The  library  of  routines  provides  an  effective  base  for  display 


depiction. 
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APPENDIX  A 

THE  LIBRARY  OF  DISPLAY  ROUTINES 
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and  the  group  information  is  sent  to  the  VDP. 
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